Person API

Overview

The Person API enables partners to manage individual person entities within the system. This API provides comprehensive functionality for creating persons, retrieving person information with advanced filtering capabilities, and managing person-related documents. All operations support full KYC data structures including personal details, identification information, address details, PEP declarations, and compliance data.

Authentication

All Person API endpoints require authentication using API Key credentials.

Required Headers

x-app-id: YOUR_ORGANIZATION_ID
X-API-Key: YOUR_API_KEY

Both headers must be present in every request. Missing or invalid credentials will result in a 401 Unauthorized response.

Endpoints

Create Person

Creates a new person entity with full KYC information.

POST /api/persons

Request Headers

Content-Type: application/json
x-app-id: YOUR_ORGANIZATION_ID
X-API-Key: YOUR_API_KEY

Request Body

The request body accepts comprehensive person information organized into multiple sections.

Core Person Fields

Field	Type	Required	Description
firstName	string	Yes	First name of the person
middleName	string	No	Middle name of the person
lastName	string	Yes	Last name of the person
fullName	string	No	Full name of the person
nationality	string	No	Nationality of the person
dob	string (ISO 8601)	No	Date of birth
email	string	No	Email address
telephone	string	No	Phone number
taxNumber	string	No	Tax identification number
birthPlace	string	No	Place of birth

Address Information

interface AddressDTO {
  addressLine1?: string;
  addressLine2?: string;
  city?: string;
  country?: string;
  postCode?: string;
}

Field	Type	Description
address	AddressDTO	Residential address of the person

Identification Information

Field	Type	Description
identificationType	string	Type of identification document
identificationNumber	string	Identification document number
identificationIssueDate	string (ISO 8601)	Date when identification was issued
identificationExpiryDate	string (ISO 8601)	Date when identification expires
proofOfAddressType	string	Type of proof of address document

Social Profiles

interface SocialProfileFieldsDTO {
  socialMedia: string;
  socialProfile: string;
}

Field	Type	Description
socialProfiles	SocialProfileFieldsDTO[]	Array of social media profiles

Politically Exposed Person (PEP) Information

interface PepDetailDTO {
  formerPosition?: string;
  resignationDate?: string (ISO 8601);
  pepPosition?: string;
  appointmentDate?: string (ISO 8601);
  relationship?: string;
}

Field	Type	Description
politicallyExposedPerson	string	PEP status declaration
pepDeclarationType	string	Type of PEP declaration (notPep, formerPep, currentlyPep, familyMemberPep, closeAssociatePep)
pepDetail	PepDetailDTO	Detailed PEP information if applicable
sanctionPerson	string	Sanction status

Financial Information

Field	Type	Description
sourceOfWealth	string	Description of source of wealth
primarySourceIncome	string[]	Array of primary income sources
primarySourceIncomeOther	string	Other income source if not in predefined list
isResidentOfUnitedStates	boolean	Whether person is a US resident
taxResidency	string[]	Array of tax residency countries

Additional Declarations

Field	Type	Description
experienceInBusiness	string	Description of business experience
relativeOrPublicPost	string	Information about relatives in public positions
isConvictedOfFelony	boolean	Whether convicted of a felony
felonyConvictionDate	string (ISO 8601)	Date of felony conviction if applicable
isInvolvedInLitigation	boolean	Whether involved in litigation
litigationDetails	string	Details of litigation if applicable

Request Example

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "telephone": "+1234567890",
  "nationality": "United States",
  "dob": "1985-06-15",
  "birthPlace": "New York",
  "address": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Apt 4B",
    "city": "New York",
    "country": "United States",
    "postCode": "10001"
  },
  "identificationType": "Passport",
  "identificationNumber": "P123456789",
  "identificationIssueDate": "2020-01-15",
  "identificationExpiryDate": "2030-01-15",
  "proofOfAddressType": "Utility Bill",
  "socialProfiles": [
    {
      "socialMedia": "LinkedIn",
      "socialProfile": "john-doe"
    }
  ],
  "politicallyExposedPerson": "No",
  "pepDeclarationType": "notPep",
  "sanctionPerson": "No",
  "sourceOfWealth": "Employment Income",
  "primarySourceIncome": ["Employment", "Savings"],
  "isResidentOfUnitedStates": true,
  "taxResidency": ["United States"],
  "experienceInBusiness": "10 years in financial services",
  "relativeOrPublicPost": "No",
  "isConvictedOfFelony": false,
  "isInvolvedInLitigation": false,
  "taxNumber": "123-45-6789"
}

Response

{
  "statusCode": 201,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "telephone": "+1234567890",
    "nationality": "United States",
    "dob": "1985-06-15T00:00:00.000Z",
    "birthPlace": "New York",
    "address": {
      "addressLine1": "123 Main Street",
      "addressLine2": "Apt 4B",
      "city": "New York",
      "country": "United States",
      "postCode": "10001"
    },
    "identificationType": "Passport",
    "identificationNumber": "P123456789",
    "identificationIssueDate": "2020-01-15T00:00:00.000Z",
    "identificationExpiryDate": "2030-01-15T00:00:00.000Z",
    "proofOfAddressType": "Utility Bill",
    "socialProfiles": [
      {
        "socialMedia": "LinkedIn",
        "socialProfile": "john-doe"
      }
    ],
    "politicallyExposedPerson": "No",
    "pepDeclarationType": "notPep",
    "sanctionPerson": "No",
    "sourceOfWealth": "Employment Income",
    "primarySourceIncome": ["Employment", "Savings"],
    "isResidentOfUnitedStates": true,
    "taxResidency": ["United States"],
    "experienceInBusiness": "10 years in financial services",
    "relativeOrPublicPost": "No",
    "isConvictedOfFelony": false,
    "isInvolvedInLitigation": false,
    "taxNumber": "123-45-6789",
    "percentageOfComplete": 75,
    "createdAt": "2025-03-15T10:30:00.000Z",
    "updatedAt": "2025-03-15T10:30:00.000Z"
  }
}

Response Fields

Field	Type	Description
statusCode	number	HTTP status code
data	PersonResponseDto	Created person object with all submitted fields plus system-generated fields

---

Get Persons

Retrieves a paginated list of persons with advanced filtering and search capabilities.

GET /api/persons

Request Headers

x-app-id: YOUR_ORGANIZATION_ID
X-API-Key: YOUR_API_KEY

Query Parameters

Parameter	Type	Required	Description
search	string	No	Search term to filter persons by name, email, or identification number
nationality	string	No	Filter by nationality
identificationType	string	No	Filter by identification type
politicallyExposedPerson	string	No	Filter by PEP status
sortBy	string	No	Field to sort by: firstName, lastName, email, nationality, createdAt, updatedAt (default: createdAt)
sortOrder	string	No	Sort direction: asc or desc (default: desc)
page	number	No	Page number for pagination (default: 1, minimum: 1)
limit	number	No	Number of items per page (default: 10, minimum: 1, maximum: 100)

Request Example

GET /api/persons?search=john&nationality=United%20States&page=1&limit=20&sortBy=firstName&sortOrder=asc

Response

{
  "statusCode": 200,
  "data": {
    "items": [
      {
        "_id": "507f1f77bcf86cd799439011",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "nationality": "United States",
        "identificationType": "Passport",
        "identificationNumber": "P123456789",
        "politicallyExposedPerson": "No",
        "percentageOfComplete": 75,
        "createdAt": "2025-03-15T10:30:00.000Z",
        "updatedAt": "2025-03-15T10:30:00.000Z"
      }
    ],
    "meta": {
      "total": 1,
      "page": 1,
      "limit": 20,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  }
}

Response Structure

interface PersonsListResponseDto {
  statusCode: number;
  data: {
    items: PersonResponseDto[];
    meta: {
      total: number;
      page: number;
      limit: number;
      totalPages: number;
      hasNextPage: boolean;
      hasPreviousPage: boolean;
    };
  };
}

Field	Type	Description
statusCode	number	HTTP status code
data.items	PersonResponseDto[]	Array of person objects matching the filters
data.meta.total	number	Total number of persons matching the query
data.meta.page	number	Current page number
data.meta.limit	number	Number of items per page
data.meta.totalPages	number	Total number of pages available
data.meta.hasNextPage	boolean	Whether there is a next page
data.meta.hasPreviousPage	boolean	Whether there is a previous page

---

Get Person by ID

Retrieves detailed information for a specific person.

GET /api/persons/{id}

Replace \{id\} with the actual person ID.

Request Headers

x-app-id: YOUR_ORGANIZATION_ID
X-API-Key: YOUR_API_KEY

Request Example

GET /api/persons/507f1f77bcf86cd799439011

Response

{
  "statusCode": 200,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "firstName": "John",
    "middleName": "Michael",
    "lastName": "Doe",
    "fullName": "John Michael Doe",
    "email": "john.doe@example.com",
    "telephone": "+1234567890",
    "nationality": "United States",
    "dob": "1985-06-15T00:00:00.000Z",
    "birthPlace": "New York",
    "address": {
      "addressLine1": "123 Main Street",
      "addressLine2": "Apt 4B",
      "city": "New York",
      "country": "United States",
      "postCode": "10001"
    },
    "identificationType": "Passport",
    "identificationNumber": "P123456789",
    "identificationIssueDate": "2020-01-15T00:00:00.000Z",
    "identificationExpiryDate": "2030-01-15T00:00:00.000Z",
    "proofOfAddressType": "Utility Bill",
    "socialProfiles": [
      {
        "_id": "507f1f77bcf86cd799439012",
        "socialMedia": "LinkedIn",
        "socialProfile": "john-doe"
      },
      {
        "_id": "507f1f77bcf86cd799439013",
        "socialMedia": "Twitter",
        "socialProfile": "johndoe"
      }
    ],
    "politicallyExposedPerson": "No",
    "pepDeclarationType": "notPep",
    "sanctionPerson": "No",
    "sourceOfWealth": "Employment Income and Investments",
    "primarySourceIncome": ["Employment", "Savings", "Investments"],
    "primarySourceIncomeOther": null,
    "isResidentOfUnitedStates": true,
    "taxResidency": ["United States"],
    "experienceInBusiness": "10 years in financial services industry",
    "relativeOrPublicPost": "No",
    "isConvictedOfFelony": false,
    "felonyConvictionDate": null,
    "isInvolvedInLitigation": false,
    "litigationDetails": null,
    "taxNumber": "123-45-6789",
    "percentageOfComplete": 85,
    "createdAt": "2025-03-15T10:30:00.000Z",
    "updatedAt": "2025-03-15T11:45:00.000Z"
  }
}

Response Structure

interface PersonResponseWrapperDto {
  statusCode: number;
  data: {
    _id: string;
    firstName: string;
    middleName?: string;
    lastName: string;
    fullName?: string;
    nationality?: string;
    dob?: string;
    email?: string;
    telephone?: string;
    taxNumber?: string;
    taxResidency?: string[];
    politicallyExposedPerson?: string;
    pepDeclarationType?: string;
    pepDetail?: {
      formerPosition?: string;
      resignationDate?: string;
      pepPosition?: string;
      appointmentDate?: string;
      relationship?: string;
    };
    sanctionPerson?: string;
    residentOfUnitedStates?: string;
    socialProfiles?: Array<{
      _id?: string;
      socialMedia: string;
      socialProfile: string;
    }>;
    experienceInBusiness?: string;
    relativeOrPublicPost?: string;
    address?: {
      addressLine1?: string;
      addressLine2?: string;
      postCode?: string;
      city?: string;
      country?: string;
    };
    identificationType?: string;
    identificationNumber?: string;
    identificationIssueDate?: string;
    identificationExpiryDate?: string;
    proofOfAddressType?: string;
    birthPlace?: string;
    sourceOfWealth?: string;
    primarySourceIncome?: string[];
    primarySourceIncomeOther?: string;
    isConvictedOfFelony?: boolean;
    felonyConvictionDate?: string;
    isInvolvedInLitigation?: boolean;
    litigationDetails?: string;
    isResidentOfUnitedStates?: boolean;
    percentageOfComplete?: number;
    createdAt: string;
    updatedAt: string;
  };
}

---

Get Person Documents

Retrieves all documents associated with a specific person, organized by document type.

GET /api/persons/{id}/documents

Replace \{id\} with the actual person ID.

Request Headers

x-app-id: YOUR_ORGANIZATION_ID
X-API-Key: YOUR_API_KEY

Request Example

GET /api/persons/507f1f77bcf86cd799439011/documents

Response

{
  "statusCode": 200,
  "data": {
    "personId": "507f1f77bcf86cd799439011",
    "personName": "John Doe",
    "documents": [
      {
        "documentField": "identificationFile",
        "folderName": "Identification Document",
        "isApplicable": true,
        "folder": {
          "_id": "66a7600c78f68e2f3ec090b3",
          "name": "Identification Document"
        },
        "documents": [
          {
            "_id": "66a7610f3e29e4d4a0b912b9",
            "fileName": "passport.pdf",
            "fileType": "application/pdf",
            "fileSize": 1024000,
            "bucket": "s3-bucket-name",
            "bucketKey": "persons/507f1f77bcf86cd799439011/identification/passport.pdf",
            "createdAt": "2025-03-15T10:35:00.000Z",
            "updatedAt": "2025-03-15T10:35:00.000Z"
          }
        ]
      },
      {
        "documentField": "proofOfAddressFile",
        "folderName": "Proof of Address",
        "isApplicable": true,
        "folder": {
          "_id": "66a7600c78f68e2f3ec090b4",
          "name": "Proof of Address"
        },
        "documents": [
          {
            "_id": "66a7610f3e29e4d4a0b912ba",
            "fileName": "utility_bill.pdf",
            "fileType": "application/pdf",
            "fileSize": 512000,
            "date": "2025-02-15",
            "bucket": "s3-bucket-name",
            "bucketKey": "persons/507f1f77bcf86cd799439011/address/utility_bill.pdf",
            "createdAt": "2025-03-15T10:36:00.000Z",
            "updatedAt": "2025-03-15T10:36:00.000Z"
          }
        ]
      },
      {
        "documentField": "cv",
        "folderName": "CV",
        "isApplicable": true,
        "folder": {
          "_id": "66a7600c78f68e2f3ec090b5",
          "name": "CV"
        },
        "documents": [
          {
            "_id": "66a7610f3e29e4d4a0b912bb",
            "fileName": "john_doe_cv.pdf",
            "fileType": "application/pdf",
            "fileSize": 256000,
            "bucket": "s3-bucket-name",
            "bucketKey": "persons/507f1f77bcf86cd799439011/cv/john_doe_cv.pdf",
            "createdAt": "2025-03-15T10:37:00.000Z",
            "updatedAt": "2025-03-15T10:37:00.000Z"
          }
        ]
      },
      {
        "documentField": "additionalDocuments",
        "folderName": "Additional Documents",
        "isApplicable": true,
        "folder": {
          "_id": "66a7600c78f68e2f3ec090b6",
          "name": "Additional Documents"
        },
        "documents": [
          {
            "_id": "66a7610f3e29e4d4a0b912bc",
            "fileName": "birth_certificate.pdf",
            "fileType": "application/pdf",
            "fileSize": 384000,
            "bucket": "s3-bucket-name",
            "bucketKey": "persons/507f1f77bcf86cd799439011/additional/birth_certificate.pdf",
            "createdAt": "2025-03-15T10:38:00.000Z",
            "updatedAt": "2025-03-15T10:38:00.000Z"
          }
        ]
      }
    ]
  }
}

Response Structure

interface PersonDocumentsResponseDto {
  statusCode: number;
  data: {
    personId: string;
    personName: string;
    documents: Array<{
      documentField: string;
      folderName: string;
      isApplicable: boolean;
      folder: {
        _id: string;
        name: string;
      };
      documents: Array<{
        _id: string;
        fileName: string;
        fileType: string;
        fileSize: number;
        date?: string;
        validity?: {
          period?: string;
          number?: number;
        };
        notice?: {
          period?: string;
          number?: number;
        };
        type?: string;
        bucket: string;
        bucketKey: string;
        createdAt: string;
        updatedAt: string;
      }>;
    }>;
  };
}

Field	Type	Description
statusCode	number	HTTP status code
data.personId	string	Person ID
data.personName	string	Full name of the person
data.documents	Array	Array of document groups, each representing a document type
documentField	string	Internal field identifier for the document type
folderName	string	Human-readable label for the document type
isApplicable	boolean	Whether this document type is applicable for the person
folder	object	Folder information where documents are stored
documents	Array	Array of files uploaded for this document type

Supported Document Types

The following document types are supported for persons:

• Identification File (Passport, National ID, Driver's License)
• Proof of Address File (Utility Bill, Bank Statement)
• CV (Curriculum Vitae)
• Additional Documents (Birth Certificate, Educational Certificates, etc.)

---

Enums and Constants

PEP Declaration Types

Value	Description
notPep	Not a Politically Exposed Person
formerPep	Former Politically Exposed Person
currentlyPep	Currently a Politically Exposed Person
familyMemberPep	Family member of a PEP
closeAssociatePep	Close associate of a PEP

Sort By Fields

Value	Description
firstName	Sort by first name
lastName	Sort by last name
email	Sort by email address
nationality	Sort by nationality
createdAt	Sort by creation date
updatedAt	Sort by last update date

Sort Order

Value	Description
asc	Ascending order
desc	Descending order

---

Error Responses

401 Unauthorized

Returned when authentication credentials are missing or invalid.

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Invalid API credentials"
}

404 Not Found

Returned when the requested person does not exist.

{
  "statusCode": 404,
  "message": "Person not found",
  "error": "Not Found"
}

400 Bad Request

Returned when the request body contains invalid data.

{
  "statusCode": 400,
  "message": ["firstName must be a string", "firstName should not be empty", "lastName must be a string", "lastName should not be empty"],
  "error": "Bad Request"
}

500 Internal Server Error

Returned when an unexpected error occurs on the server.

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

---

Data Validation Rules

Required Fields

The following fields are required when creating a person:

• firstName
• lastName

Conditional Validation

1. Tax Residency

   • Cannot be provided if isResidentOfUnitedStates is null or undefined
   • Should not be provided if person is a US resident (isResidentOfUnitedStates is true)

2. Felony Information

   • felonyConvictionDate is required only if isConvictedOfFelony is true
   • felonyConvictionDate should not be provided if isConvictedOfFelony is false

3. Litigation Information

   • litigationDetails is required only if isInvolvedInLitigation is true
   • litigationDetails should not be provided if isInvolvedInLitigation is false

4. PEP Information

   • pepDetail should be provided only if pepDeclarationType indicates PEP status
   • For formerPep: formerPosition and resignationDate are relevant
   • For currentlyPep: pepPosition and appointmentDate are relevant
   • For familyMemberPep or closeAssociatePep: relationship is relevant

Field Format

• Dates: Must be in ISO 8601 format (YYYY-MM-DD or full ISO timestamp)
• Email: Must be a valid email format
• Arrays: Can contain multiple values for fields like primarySourceIncome, taxResidency, socialProfiles

---

Usage Notes

1. All endpoints require valid API credentials in the request headers.
2. Person creation validates that required fields (firstName, lastName) are provided.
3. Dates should be provided in ISO 8601 format (YYYY-MM-DD or full ISO timestamp).
4. Array fields accept multiple values where applicable.
5. The search parameter in GET /api/persons searches across firstName, lastName, email, and identificationNumber fields (case-insensitive).
6. Pagination is 1-indexed, with page 1 being the first page.
7. Default sorting is by creation date in descending order (newest first).
8. The limit parameter has a maximum value of 100 items per page.
9. Document URLs are temporary and should be accessed within the validity period.
10. The system automatically creates folder structures for document storage when a person is created.
11. The percentageOfComplete field is automatically calculated based on filled fields and uploaded documents.
12. Soft delete is implemented - deleted persons are excluded from queries automatically.
13. All MongoDB ObjectIds are automatically serialized to strings in API responses.
14. Tax residency and US resident fields have interdependent validation rules.
15. PEP-related fields should be filled based on the pepDeclarationType value.